3D Graphics Programming with QuickDraw 3D 1.5.4

Naming Conventions

The QuickDraw 3D application programming interfaces are designed, as much as possible, to mirror the QuickDraw 3D class hierarchy described in the chapter "QuickDraw 3D Objects." They are also designed to exhibit as much uniformity as can reasonably be achieved by names describing a large and heterogeneous collection of objects instantiating classes in that hierarchy. Ideally, once you are acquainted with the various conventions governing the programming interfaces and the class hierarchy, you should be able to make correct guesses about the names of constants, data structures, and routines. In very many cases, the names of constants and routines are largely self-documenting, thanks to a strict adherence to the naming conventions. This section describes those conventions and provides some examples.

Constants

All constants defined in the QuickDraw 3D application programming interfaces have the prefix kQ3 . Very simple constants consist solely of the kQ3 prefix and a specific value indicator. Here are some examples:



 
typedef enum TQ3Boolean {

    kQ3False,

    kQ3True

} TQ3Boolean;



 
typedef enum TQ3Switch {

    kQ3Off,

    kQ3On

} TQ3Switch;



 
typedef enum TQ3Status {

    kQ3Failure,

    kQ3Success

} TQ3Status;

Most other enumerated constants consist of the standard kQ3 prefix, followed by a type, followed by a specific value. Here are some examples:



 
typedef enum TQ3Axis {

    kQ3AxisX,

    kQ3AxisY,

    kQ3AxisZ

} TQ3Axis;

Other constants are defined using the C preprocessor #define mechanism. Here are some examples:



 
#define kQ3ObjectTypeElement            Q3_OBJECT_TYPE('e','l','m','n')

#define kQ3ObjectTypePick               Q3_OBJECT_TYPE('p','i','c','k')

#define kQ3ObjectTypeShared             Q3_OBJECT_TYPE('s','h','r','d')

#define kQ3ObjectTypeView               Q3_OBJECT_TYPE('v','i','e','w')

#define kQ3ObjectTypeInvalid            0

In general, these kinds of constants specify types of objects in the QuickDraw 3D class hierarchy or methods defining the behaviors of those types. These constants use the macros Q3_OBJECT_TYPE or Q3_METHOD_TYPE . See the header file QD3D.h for definitions of these macros.

Data Types

All data structures and data types defined in the QuickDraw 3D application programming interfaces have the prefix TQ3 . Like constant names, data type names never contain the underscore character (_ ). When emphasis is required, subwords of a data type name are capitalized and usually proceed from general to specific.

There are four distinguishable classes in data type names.

Opaque objects, whose definitions are private, begin with the prefix TQ3 and end with the suffix Object . Between the prefix and the suffix are one or more words indicating the type of the opaque object. Here are some examples:



 
    TQ3GeometryObject

    TQ3ViewObject

    TQ3CameraObject

    TQ3StyleObject

    TQ3DrawContextObject

Data structures used in defining characteristics of opaque objects begin with the prefix TQ3 and end with the suffix Data . Between the prefix and the suffix are one or more words indicating the type of the object. Here are some examples:



 
    TQ3TriangleData

    TQ3BoxData

    TQ3OrthographicCameraData

Data structures that contain data not specifically used to define characteristics of an opaque object begin with the prefix TQ3 . Following the prefix are one or more words indicating the type of the data the structure contains. Here are some examples:



 
    TQ3Point3D

    TQ3Vector2D

    TQ3ColorRGB

    TQ3ColorARGB

Attributes are opaque objects, but they are named differently to distinguish them from other opaque objects. Attributes are of type TQ3Attribute .

All floating-point numbers used in the QuickDraw 3D application programming interfaces are single precision.

Functions

All functions defined in the QuickDraw 3D application programming interfaces have the prefix Q3 . The class of an identifier immediately follows its type prefix. Then the method occurs, separated from the class by an underscore. A method is almost always expressed as a verb-noun sequence. Here are some examples:



 
Q3Polygon_GetVertexPosition

Q3NURBCurve_SetControlPoint

Q3Light_SetBrightness

Q3SpotLight_GetFallOff

Q3View_GetLocalToWorldInverseTransposeMatrixState

Q3Triangle_New

Some functions are so simple that they have no distinguishable class and method. Here are some examples:



 
Q3Initialize

Q3IsInitialized

Q3Exit

As much as possible, function parameters are ordered consistently throughout the application programming interfaces. In virtually all cases, the first parameter is a data type that corresponds to the object being operated on. When there are two or more additional parameters, they are placed in their natural or intuitive ordering.

Most QuickDraw 3D functions return a status code, which is of type TQ3Status . A status code is either kQ3Success or kQ3Failure , indicating that the function has succeeded or failed. When a function fails, you can call a further function to get a specific error code. Alternatively, you can install an error-reporting callback routine to handle failures. See the chapter "Error Manager" for complete details on handling errors.

Functions that create opaque objects usually return a function result whose type is a reference to the type of the newly created object (for instance, TQ3CameraObject for a new camera object). An object reference is an opaque pointer to the object. When these kinds of routines fail, they return the value NULL .